/////////////////////////////////////////////////////////////////////////////
// This file is part of the "Java-DAP" project, a Java implementation
// of the OPeNDAP Data Access Protocol.
//
// Copyright (c) 2007 OPeNDAP, Inc.
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//
// You can contact OPeNDAP, Inc. at PO Box 112, Saunderstown, RI. 02874-0112.
/////////////////////////////////////////////////////////////////////////////
using System;
using System.IO;
using NDODS.DAP.BaseTypes;

namespace NDODS.DAP.Server
{
    /// <summary> 
    /// 
    /// </summary>
    /// <version>  $Revision: 16122 $
    /// </version>
    /// <author>  ndp
    /// </author>
    /// <seealso cref="BaseType">
    /// </seealso>
    /// <seealso cref="DDS">
    /// </seealso>
    /// <summary> This interface defines the additional behaviors that Server side types
    /// need to support. These include:
    /// <p/>
    /// <p>The file I/O operations of which each variable must be capable.
    /// <p/>
    /// <p>The projection information. A projection defines the variables
    /// specified by a constraint to be returned by the server. These methods
    /// store projection information for a non-vector variable. Each variable
    /// type used on the server-side of OPeNDAP must implement this interface or
    /// one of its descendents.
    /// <p/>
    /// <p>The methods that define how each type responds to relational
    /// operators. Most (all?) types will not have sensible responses to all of
    /// the relational operators (e.g. SDByte won't know how to match a regular
    /// expression but SDString will). For those operators that are nonsensical a
    /// class should throw InvalidOperator.
    /// 
    /// </summary>
    /// <author>  jhrg & ndp
    /// </author>
    /// <version>  $Revision: 16122 $
    /// </version>
    /// <seealso cref="IServerArrayMethods">
    /// </seealso>
    /// <seealso cref="Operator">
    /// </seealso>
    public interface IServerMethods
    {
        //UPGRADE_NOTE: Respective javadoc comments were merged.  It should be changed in order to comply with .NET documentation conventions. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1199'"
        /// <summary> Get the value of the IsRead property.
        /// 
        /// </summary>
        /// <returns> <code>true</code> if the variable has been Read,
        /// <code>false</code> otherwise.
        /// </returns>
        /// <seealso cref="Read">
        /// </seealso>
        /// <summary> Set the IsRead property. A normal variable is Read using the
        /// <code>Read()</code> method. Once Read the <em>IsRead</em> property is
        /// <code>true</code>. Use this function to manually set the property
        /// value. By default this property is false.
        /// 
        /// </summary>
        /// <seealso cref="Read">
        /// </seealso>
        bool IsRead { get; set; }

        //    FileIO interface

        /// <summary> Set the Synthesized property.
        /// 
        /// </summary>
        /// <param name="state">If <code>true</code> then the variable is considered a
        /// synthetic variable and no part of OPeNDAP will ever try to Read it from a
        /// file, otherwise if <code>false</code> the variable is considered a
        /// normal variable whose value should be Read using the
        /// <code>Read()</code> method. By default this property is false.
        /// </param>
        /// <seealso cref="IsSynthesized">
        /// </seealso>
        /// <seealso cref="Read">
        /// </seealso>
        void setSynthesized(bool state);

        /// <summary> Get the value of the Synthesized property.
        /// 
        /// </summary>
        /// <returns> <code>true</code> if this is a synthetic variable,
        /// <code>false</code> otherwise.
        /// </returns>
        bool IsSynthesized();

        /// <summary> IsRead a value from the named dataset for this variable.
        /// 
        /// </summary>
        /// <param name="datasetName">String identifying the file or other data store
        /// from which to Read a vaue for this variable.
        /// </param>
        /// <param name="specialO">   This <code>Object</code> is a goody that is used by a
        /// Server implementations to deliver important, and as
        /// yet unknown, stuff to the Read method. If you don't
        /// need it, make it a <code>null</code>.
        /// </param>
        /// <returns> <code>true</code> if more data remains to be Read, otehrwise
        /// <code>false</code>.
        /// </returns>
        /// <throws>  NoSuchVariableException When a variable can't be found. </throws>
        /// <throws>  IOException When there is a problem reading data. </throws>
        bool Read(String datasetName, Object specialO);

        // Projection Interface

        /// <summary> Set the state of this variable's projection. <code>true</code> means
        /// that this variable is part of the current projection as defined by
        /// the current constraint expression, otherwise the current projection
        /// for this variable should be <code>false</code>.<p>
        /// <p/>
        /// For simple variables and for children of DVector, the variable either
        /// is or is not projected. For children of DConstructor, it may be that
        /// the request is for only part of the constructor type (e.g., only oe
        /// field of a structure). However, the structure variable itself must be
        /// marked as projected given the implementation of serialize. The
        /// serialize() method does not Search the entire tree of variables; it
        /// relies on the fact that for a particular variable to be sent, the
        /// <em>path</em> from the top of the DDS to that variable must be marked
        /// as `projected', not just the variable itself. This keeps the
        /// CEEvaluator.send() method from having to Search the entire tree for
        /// the variables to be sent.
        /// 
        /// </summary>
        /// <param name="state"><code>true</code> if the variable is part of the current
        /// projection, <code>false</code> otherwise.
        /// </param>
        /// <param name="all">  set (or clear) the Project property of any children.
        /// </param>
        /// <seealso cref="CEEvaluator">
        /// </seealso>
        void setProject(bool state, bool all);

        /// <summary> Set the Project property of this variable. This is equivalent to
        /// calling setProject(<state>, true).
        /// 
        /// </summary>
        /// <param name="state"><code>true</code> if the variable is part of the current
        /// projection, <code>false</code> otherwise.
        /// </param>
        /// <seealso cref="setProject(bool)">
        /// </seealso>
        /// <seealso cref="CEEvaluator">
        /// </seealso>
        void setProject(bool state);

        /// <summary> Check the projection state of this variable.
        /// Is the this variable marked as projected? If the variable is listed
        /// in the projection part of a constraint expression, then the CE parser
        /// should mark it as <em>projected</em>. When this method is called on
        /// such a variable it should return <code>true</code>, otherwise it
        /// should return <code>false</code>.
        /// 
        /// </summary>
        /// <returns> <code>true</code> if the variable is part of the current
        /// projections, <code>false</code> otherwise.
        /// </returns>
        /// <seealso cref="setProject(bool,bool)">
        /// </seealso>
        /// <seealso cref="setProject(bool)">
        /// </seealso>
        /// <seealso cref="CEEvaluator">
        /// </seealso>
        bool isProject();

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when they are equal, false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool equal(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when they are not equal, false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <seealso cref="Operator">
        /// </seealso>
        bool not_equal(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when this value is greater than the based 'bt' value,
        /// false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool greater(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when this value is greater or equal than the based 'bt' value,
        /// false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool greater_eql(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when this value is less than the based 'bt' value,
        /// false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool less(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when this value is less than or equal to the based 'bt' value,
        /// false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool less_eql(BaseType bt);

        /// <summary> The <code>Operator</code> class contains a generalized implementation
        /// of this method. It should be used unless a localized
        /// architecture/implementation requires otherwise.
        /// 
        /// </summary>
        /// <param name="bt">The variable to which to compare 'this' value.
        /// </param>
        /// <returns> True when regular expression evaluates to true.,
        /// false otherwise.
        /// </returns>
        /// <throws>  InvalidOperatorException When the operator cannot be applied to </throws>
        /// <summary> the two data types.
        /// </summary>
        /// <throws>  RegExpException When the regular expression is badly formed. </throws>
        /// <throws>  SBHException When Something Bad Happens. </throws>
        /// <summary> 
        /// </summary>
        /// <seealso cref="Operator">
        /// </seealso>
        bool regexp(BaseType bt);


        /// <summary> Server-side serialization for OPeNDAP variables (sub-classes of
        /// <code>BaseType</code>). This does not send the entire class as the
        /// Java <code>Serializable</code> interface does, rather it sends only
        /// the binary data values. Other software is responsible for sending
        /// variable type information (see <code>DDS</code>).<p>
        /// <p/>
        /// Writes data to a <code>DataOutputStream</code>. This method is used
        /// on the server side of the OPeNDAP client/server connection, and possibly
        /// by GUI clients which need to download OPeNDAP data, manipulate it, and
        /// then re-save it as a binary file.<p>
        /// <p/>
        /// For children of DConstructor, this method should call itself on each
        /// of the components. For other types this method should call
        /// Externalize().
        /// 
        /// </summary>
        /// <param name="dataset">a <code>String</code> indicated which dataset to Read
        /// from (Or something else if you so desire).
        /// </param>
        /// <param name="sink">   a <code>DataOutputStream</code> to write to.
        /// </param>
        /// <param name="ce">     the <code>CEEvaluator</code> to use in the parse process.
        /// </param>
        /// <param name="specialO">   This <code>Object</code> is a goody that is used by a
        /// Server implementations to deliver important, and as
        /// yet unknown, stuff to the Read method. If you don't
        /// need it, make it a <code>null</code>.
        /// </param>
        /// <throws>  IOException thrown on any <code>OutputStream</code> exception. </throws>
        /// <throws>  NDODS.DAP.NoSuchVariableException When a variable cannot be found. </throws>
        /// <throws>  DAP2ServerSideException When there is a server error. </throws>
        /// <seealso cref="BaseType">
        /// </seealso>
        /// <seealso cref="DDS">
        /// </seealso>
        /// <seealso cref="ServerDDS">
        /// </seealso>
        //UPGRADE_TODO: Class 'java.io.DataOutputStream' was converted to 'System.IO.BinaryWriter' which has a different behavior. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1073_javaioDataOutputStream'"
        void serialize(String dataset, BinaryWriter sink, CEEvaluator ce, Object specialO);
    }
}